The Expression Builder lets users manipulate and save targeting expressions.
These expressions are represented in XML, and are stored in the BizData
Store. The Expression Builder widget uses the Query Builder widget to let
users manipulate the expression body.
This page demonstrates the basic functionality of the Expression Builder.
It also contains a basic description of the Expression Builder's
programmatic interface.
Demo
Loading the Expression Builder...
/retailbizdesk/exprarch
events
onReady
Indicates that the Expression Builder is fully loaded and initialized,
and that its programmatic interface is ready to use. Any app that
intends to interact with the Expression Builder's programmatic
interface should ensure that they do this AFTER this event fires.
event object properties
none
onComplete
This event fires when the Expression Builder has been successfully
terminated, either by the user pressing "Save" or "Cancel" buttons,
and no errors taking place in the save/cancel operations.
event object properties
none
onError
This event fires when activation of the Expression Builder fails at
any point. Keep in mind that the Activate method may return a success
value, but an onError event later fires as well because some
unexpected error takes place as activation continues. No error message
is returned with the event, but if the Expression Builder is in debug
mode, an error is displayed to the user before the event fires.
event object properties
none
methods
bSuccess = divExprBldr.Activate(sMode, nExprID)
Activates the Expression Builder. The arguments specify the ID of the
expression to load, and the mode of operation to load it in as. The
arguments must be the following:
parameters
sMode (Required) String. See table below.
nExprID (Required) Integer. See table below.
sMode
nExprID
"create"
any number; nExprID is ignored
"createfrom"
the ID of a valid expression in the store
"edit"
the ID of a valid expression in the store
"view"
the ID of a valid expression in the store
return value
bSuccess Boolean. If a fatal error occurs during this
function's operation, returns false. Otherwise it returns
true.
divExprBldr.Deactivate()
Deactivates the Expression Builder and disables all controls.
parameters
none
return value
none
dictResults = divExprBldr.GetResults()
Returns the current Expression Builder status / results.
parameters
none
return value
dictResults Scripting.Dictionary.
The following values are present on this object:
Key (string)
Value
'SavedExpr'
This value is true if the current expression has been
successfully saved (i.e. a successful "create" or "save"
operation), or false if the current expression has not
been saved.
'ExprID'
ID of the expression that was created/edited/viewed. If a new
expression is being created and it hasn't been saved yet, this
will be -1 (EXPRID_INVALID).
'ExprName'
Current name of the expression. If the user is still performing
edits when the GetResults() method is called, the current value
of the expression name is returned, not the previous name.
'ExprBody'
XML of the expression body. If the user is still performing
edits when the GetResults() method is called, the current value
of the expression body XML is returned, not the previous
expression body XML.
divExprBldr.Save()
Saves the current expression changes, if the Expression Builder is in
the appropriate mode.
parameters
none
return value
none
remarks
This method is identical to having the user actually push the "Save"
button; it simply provides a programmatic way of saving the expression.
Thus, it will fire an onComplete event if the save operation succeeds.
divExprBldr.Cancel()
Cancels editing.
parameters
none
return value
none
remarks
This method is identical to having the user actually push the "Cancel"
button; it simply provides a programmatic way of cancelling.
Thus, it will fire an onComplete event if the save operation succeeds.
Also, if changes have been made to the profile, the user will be notified
that changes will be lost.
container attributes (set on element)
XMLConfigID
ID of an XML data-island from which the Expression Builder can load its
configuration information.
scriptable properties
bReady = divExprBldr.IsReady
Indicates whether the Expression Builder is ready or not. This
property is false before the onReady event fires, and is true
after the onReady event fires. It is provided so that external
components can determine if the Expression Builder is ready to be used
without using events.
bActive = divExprBldr.IsActive
Indicates whether the Expression Builder is currently active or not.
This property is true when the Expression Builder is active (ie. the
user can interact with the Expression Builder) and false when it is
inactive.
Configuration XML
<EBCONFIG>
<EXPR-ASP> - Required.
Specifies the URL used to access the exprarch subdirectory of the
BizDesk site. This is essential for the Expression Builder to work
correctly.
<PROFILE-LIST> - Required.
Specifies profiles to be used by Expression Builder.
<PROFILE*> - Required (at least one).
Contains the path to a UPM profile to be retrieved, or has a
SRC attribute.
@SRC - Optional.
Alternate source to retrieve a non-UPM profile. The URL must
retrieve a valid XML document that contains one or more profiles.
<DEBUG> - Optional.
If present, causes Expression Builder to display debug info.
<RENAME> - Optional.
Specifies whether Expression Builder allows renaming of
expressions when used for editing. If inner text of tag is "no",
renaming is not allowed. Any other value or absence of tag allows
renaming.
<HIDEBUTTONS> - Optional.
Specifies whether Expression Builder hides its Save, Cancel and Help
buttons. If tag is present, buttons are hidden.
<HELPTOPIC> - Optional.
Inner text is a URL to display a help topic. If this tag is present,
help buttons will be displayed in Expression Builder. Otherwise, help
buttons will not be displayed.
<FILTER-CATEGORIES> - Optional.
Specifies what categories to filter against when retrieving a list of
expressions to be used in building this expression.
<CATEGORY*> - Optional.
Inner text specifies a category.
<SAVE-CATEGORY> - Optional.
Inner text specifies the category to save for this expression when
it is saved. Overwrites the previously-specified category, if one
was specified. If this tag is not specified, the SAVE-CATEGORY
is the same as when it was loaded.
<EEE-INTRINSICS> - Optional.
If present, causes the Expression Builder to expose the Expression
Evaluator's intrinsic properties as a profile in the dropdown menus.
<TYPESOPS> - Optional.
Inner text specifies the types/operators file that the Expression
Builder is to use. If this tag is not specified, the default is
"/widgets/exprbldrHTC/TypesOpsA.xml".
<SITE-TERMS> - Optional.
Specifies alternate information about whether the Query Builder
should load site-terms, and if so, where from.
@NOLOAD - Optional.
If this attribute is equal to "1", Expression Builder will
not load site-terms. Note that if expressions with site-terms
are loaded, errors will occur.
@URL - Optional.
If the NOLOAD attribute is not equal to "1", this attribute
specifies an alternate source to load site-terms. The URL must
retrieve a valid XML document that defines site-terms.
<EDIT-NESTED> - Optional.
Inner text must be "warn", "always", or "never". Default is "never".
Determines whether a user may edit a nested expression. "Warn" will
cause the user to be prompted whether to edit or view the expression.
"Always" will always allow the user to edit the expression, while
"never" will cause the nested expression to be displayed in read-only
mode.
<MESSAGE> - Optional.
Inner text specifies the prompt text above the Clause List. When this tag
isn't specified, the default message is "Target according to the
following conditions".
<FILTER-PROPERTIES> - Optional.
Inner text specifies an XSL pattern (fragment) to use for filtering
properties from the profile. If this tag is set, the XSL pattern
will be applied to the properties in each profile loaded into
Expression Builder. Any properties not fitting the XSL pattern
will not be shown in the builder when creating/editing expressions.
The default XSL pattern match for properties is:
not(@isActive) || @isActive != '0'
If the FILTER-PROPERTIES is set, it will override the default pattern.
Note: The actual XSL pattern uses this string surrounded by
"PROPERTY[" and "]", i.e., the default pattern is
"PROPERTY[not(@isActive) || @isActive != '0']"
XSL Note: Attributes on nodes will return '0' if they are not defined,
therefore it is recommended that any expressions include a statement
to compare the return value to '0' and take the default action if the
attribute is not present.
<DATE-FORMAT> - Optional.
Inner text specifies the date data entry format. The default is
m/d/y.
<DATE-FIRSTDAY> - Optional.
Inner text specifies the first day of the week used when displaying the
calendar. Valid values are 0-6. The default is 0 (0=Sun, 1=Mon, etc).
<NUMBER-FORMAT> - Optional.
Inner text specifies the number data entry format. The default is
-1.1.
<CURRENCY-FORMAT> - Optional.
Inner text specifies the currency data entry format. The default is
-1.1.
<ADVANCED> - Optional.
If present, causes Expression Builder to load in advanced mode.
Advanced mode exposes the ability to use 'OR' in expressions.
By default, basic mode is used.